docs: focus README on safe cache rollouts - #89

Summary

• replace the 14,228-word single-page README on current main with a 2,918-word adoption guide that identifies DialCache as a TypeScript read-through caching library before introducing its production patterns
• explain the execution model up front: wrap a reusable reader with cached() or keep a loader inline with getOrLoad(); after active layers miss, DialCache calls the application loader and publishes to active request-local, bounded process-local, and optional Redis or Valkey layers
• make the ownership boundary explicit: DialCache is an application library, not a frontend cache, cache server, Redis client, or configuration control plane
• lead production adoption through explicit enablement, zero-ramp starting policy, deterministic ramp-up and ramp-down, observability, optional non-serving shadow validation, and reversible kill switches
• move complete configuration, Redis/Valkey, shadow, invalidation, coalescing/liveness, observability, and release contracts into seven focused reference guides
• use absolute GitHub file URLs for every README-to-repository link so the packaged README renders correctly on npm even though docs/ is not part of the package tarball

Why

The current README is technically thorough but makes experienced backend engineers work too hard to establish the basic mental model: what kind of cache this is, what happens on a miss, which layers it manages, which high-scale patterns it adds, and which infrastructure and safety decisions remain application-owned.

The revised README answers those questions before setup, gives a copyable local-only quick start, then shows the path from local verification to a safe production rollout. Detailed contracts remain available without turning the README back into the full reference manual.

Current-main refresh

This branch now includes current main through v0.19.0 plus the Redis-write benchmark update, and documents the public behavior added since the prior v0.14.1 refresh:

• tracked and untracked shadow validation, including same-mode reads and fills, tracked watermark fencing, untracked TTL last-writer-wins behavior, and the v0.15.0 upgrade consideration
• default-on per-use-case coalescing with the sparse coalesce: false opt-out, independent reads/deadlines/writes, observability effects, and thundering-herd tradeoff
• native untracked GET and atomic tracked MGET reads, including authoritative routing requirements and stale-payload transfer
• default-on zstd compression, exact Node.js engine range, synchronous event-loop cost, size caps, metrics, failure behavior, and mixed-version rollout/rollback guidance
• native untracked SET and tracked placeholder-plus-stamp writes, including nonce safety, ambiguity, placeholder-loss errors, adapter lifecycle, ACLs, and current protocol exports
• invalidation cleanup and write-amplification costs under future watermarks
• the new eight-configuration Redis-write benchmark, including its dedicated-Redis and CONFIG RESETSTAT safety requirements

Impact

This is documentation-only relative to current main.

Merging this PR will not republish v0.19.0; the rewritten README will appear on npm with a future package release. Its absolute links will resolve to the merged reference guides on main.

Validation

• corepack pnpm check under Node.js 22.22.0 — strict typecheck, 512 unit tests with coverage, builds/declarations, and packed ESM/CJS consumers
• corepack pnpm test:integration — suite passed with 139 cases collected (137 passed, 2 environment-skipped)
• corepack pnpm benchmark:request-local — all ten semantic scenarios passed
• corepack pnpm benchmark:redis-write against a disposable Redis 6.2 — all eight tracked/untracked size configurations completed
• syntax-checked all 28 TypeScript documentation blocks
• validated 82 Markdown links; every local file and anchor resolves
• README contains 22 absolute repository-file links and zero relative repository-file links
• longest non-list prose paragraph across the README and guides is 70 words
• git diff --check
• fresh technical, editorial, npm-consumer, and source-accuracy review; all findings were fixed and the final confirmation passes returned clean
• fresh exact-head GitHub checks passed: package CI, both CodeQL analyses, and PR-title validation